/**
 * 个人预算管理系统 - 服务器入口文件
 * 
 * 主要功能：
 * 1. 初始化Express应用
 * 2. 配置安全中间件（helmet、cors）
 * 3. 配置请求解析中间件
 * 4. 配置API限流
 * 5. 注册所有路由模块
 * 6. 统一错误处理
 * 7. 启动HTTP服务器
 * 
 * @author 个人预算管理系统开发团队
 * @date 2025-10-26
 */

// ==================== 依赖导入 ====================
const express = require('express');           // Express Web框架
const cors = require('cors');                 // 跨域资源共享中间件
const helmet = require('helmet');             // HTTP安全头中间件
const rateLimit = require('express-rate-limit'); // API限流中间件
const path = require('path');                 // 路径处理模块
require('dotenv').config();                   // 加载环境变量

// ==================== 应用初始化 ====================
const app = express();                        // 创建Express应用实例
const PORT = process.env.PORT || 3000;       // 服务器端口（默认3000）

// 🎮 游戏化功能自动初始化模块
// 用于在服务器启动时自动初始化游戏化系统（成就、等级等）
const initGamification = require('./config/init-gamification');

// ==================== 安全中间件配置 ====================

/**
 * Helmet安全中间件
 * 功能：设置各种HTTP安全响应头，防止常见的Web漏洞
 * 包括：XSS防护、点击劫持防护、内容类型嗅探防护等
 */
app.use(helmet());

/**
 * CORS跨域配置
 * 功能：允许前端跨域访问后端API
 * 
 * 配置说明：
 * - origin: 允许的源（开发环境允许所有来源，包括file://协议）
 * - credentials: 允许携带认证信息（cookies、authorization headers）
 */
app.use(cors({
    origin: function (origin, callback) {
        // 允许所有来源，包括没有origin的请求（如file://协议）
        callback(null, true);
    },
    credentials: true
}));

// ==================== 请求解析中间件 ====================

/**
 * JSON请求体解析
 * 功能：自动解析Content-Type为application/json的请求体
 */
app.use(express.json());

/**
 * URL编码请求体解析
 * 功能：解析Content-Type为application/x-www-form-urlencoded的请求体
 * extended: true 使用qs库解析，支持嵌套对象
 */
app.use(express.urlencoded({ extended: true }));

// ==================== API限流配置 ====================

/**
 * 全局API限流器
 * 功能：防止恶意频繁请求，保护服务器资源
 * 
 * 配置参数：
 * @param {number} windowMs - 时间窗口（15分钟 = 900000毫秒）
 * @param {number} max - 时间窗口内最大请求数（500次）
 * @param {object} message - 超限时返回的错误消息
 * @param {boolean} standardHeaders - 返回标准的RateLimit-* 响应头
 * @param {boolean} legacyHeaders - 不返回X-RateLimit-* 响应头（旧版）
 * 
 * 设计思路：
 * 1. 15分钟内最多500次请求，适合页面频繁切换的场景
 * 2. 比默认的100次更宽松，提升用户体验
 * 3. 足够阻止恶意攻击，但不影响正常使用
 */
const generalLimiter = rateLimit({
    windowMs: 15 * 60 * 1000,  // 15分钟时间窗口
    max: 500,                   // 最多500个请求
    message: { 
        code: 429, 
        message: '请求过于频繁，请稍后再试' 
    },
    standardHeaders: true,      // 使用标准的RateLimit响应头
    legacyHeaders: false,       // 禁用旧版X-RateLimit响应头
});

// 将限流器应用到所有/api路由
app.use('/api/', generalLimiter);

// ==================== 静态文件服务 ====================

/**
 * 静态文件服务配置
 * 功能：提供前端HTML、CSS、JS等静态资源
 * 路径：../src 目录（相对于backend目录）
 */
app.use(express.static(path.join(__dirname, '../src')));

// ==================== 路由注册 ====================

/**
 * 注册所有API路由模块
 * 
 * 路由说明：
 * - /api/auth: 用户认证相关（注册、登录、验证Token等）
 * - /api/books: 账本管理（创建、查询、更新、删除、分享）
 * - /api/records: 收支记录（添加、查询、修改、删除）
 * - /api/stats: 数据统计（基础统计、分类统计、趋势分析）
 * - /api/budgets: 预算管理（设置预算、查询预算使用情况）
 * - /api/quick-items: 快捷记账项（预设常用记账项目）
 * - /api/features: 功能开关（控制功能是否启用）
 * - /api/advanced: 高级功能（数据导出、批量操作等）
 * - /api/gamification: 游戏化功能（成就、等级、积分系统）
 * - /api/import: 账单导入功能（微信、支付宝账单导入）📥 新增
 */
app.use('/api/auth', require('./routes/auth'));
app.use('/api/books', require('./routes/books'));
app.use('/api/records', require('./routes/records'));
app.use('/api/stats', require('./routes/stats'));
app.use('/api/budgets', require('./routes/budgets'));
app.use('/api/quick-items', require('./routes/quick-items'));
app.use('/api/features', require('./routes/features'));
app.use('/api/advanced', require('./routes/advanced-features'));
app.use('/api/gamification', require('./routes/gamification')); // 🎮 游戏化功能
app.use('/api/import', require('./routes/import')); // 📥 账单导入功能
app.use('/api/analysis', require('./routes/analysis')); // 📊 智能分析功能

// ==================== 健康检查接口 ====================

/**
 * 健康检查端点
 * 
 * @route GET /health
 * @description 用于监控系统运行状态，返回服务器当前时间戳
 * @returns {object} 200 - 成功响应
 * @returns {object} 200.status - 状态标识（固定为'ok'）
 * @returns {string} 200.timestamp - 服务器当前时间（ISO 8601格式）
 * 
 * @example
 * // 响应示例
 * {
 *   "status": "ok",
 *   "timestamp": "2025-10-26T12:00:00.000Z"
 * }
 */
app.get('/health', (req, res) => {
    res.json({ 
        status: 'ok', 
        timestamp: new Date().toISOString() 
    });
});

// ==================== 404错误处理 ====================

/**
 * 404错误处理中间件
 * 
 * @description 捕获所有未匹配的路由，返回404错误
 * @param {object} req - Express请求对象
 * @param {object} res - Express响应对象
 * @returns {object} 404 - 资源不存在响应
 * 
 * 设计思路：
 * 1. 放在所有路由之后，捕获所有未匹配的请求
 * 2. 统一返回JSON格式的错误信息
 * 3. 便于前端统一处理404错误
 */
app.use((req, res) => {
    res.status(404).json({ 
        code: 404, 
        message: '接口不存在' 
    });
});

// ==================== 全局错误处理 ====================

/**
 * 全局错误处理中间件
 * 
 * @description 捕获所有未处理的错误，统一返回错误响应
 * @param {Error} err - 错误对象
 * @param {object} req - Express请求对象
 * @param {object} res - Express响应对象
 * @param {function} next - Express next函数
 * @returns {object} 500 - 服务器错误响应
 * 
 * 设计思路：
 * 1. 在开发环境返回详细错误信息，便于调试
 * 2. 在生产环境隐藏错误细节，保护系统安全
 * 3. 所有错误都记录到控制台，便于排查问题
 * 4. 统一的错误响应格式，便于前端处理
 */
app.use((err, req, res, next) => {
    // 记录错误堆栈到控制台（包含详细的错误信息和调用栈）
    console.error(err.stack);
    
    // 返回错误响应
    res.status(500).json({ 
        code: 500, 
        message: '服务器错误',
        // 仅在开发环境返回详细错误信息
        error: process.env.NODE_ENV === 'development' ? err.message : undefined 
    });
});

// ==================== 服务器启动 ====================

/**
 * 启动HTTP服务器
 * 
 * @description 启动Express应用，监听指定端口
 * @async
 * 
 * 启动流程：
 * 1. 绑定端口并启动HTTP服务器
 * 2. 输出启动成功信息到控制台
 * 3. 自动初始化游戏化功能（成就、等级等）
 * 
 * 设计思路：
 * 1. 使用环境变量配置端口，便于部署
 * 2. 异步初始化游戏化功能，不阻塞服务器启动
 * 3. 输出友好的启动信息，包含访问地址
 */
app.listen(PORT, async () => {
    console.log(`✅ 服务器运行在 http://localhost:${PORT}`);
    console.log(`📚 API文档: http://localhost:${PORT}/api`);
    
    // 🎮 自动初始化游戏化功能
    // 包括：初始化成就系统、等级系统、检查数据库表是否存在等
    await initGamification();
}); 